
%\documentstyle[times,titlepage,twoside,verbatimfiles]{article}
\documentstyle[titlepage,twoside,verbatimfiles]{article}

% margins from ~/tex/opengl/*.tex documents
\topmargin -0.3in
\headheight 10pt
\headsep 15pt
\oddsidemargin -.20in
\evensidemargin -.35in
\textwidth 7.1in
\textheight 9in
\makeindex

\begin{document}

% index a routine name
\def\rndx#1{{\index{#1}\tt #1}}
% index a word
\def\ndx#1{{\index{#1}#1}}

\pagestyle{headings}

\newcounter{NoteNum}
\def\resetNote{\setcounter{NoteNum}{0}}
\def\takeNote{\addtocounter{NoteNum}{1}(\theNoteNum)}
\def\sameNote{(\theNoteNum)}

\title{ 
{\huge
The OpenGL Utility Toolkit (GLUT) Programming Interface} \\
\vspace{.4in}
API Version 2}
\author{Mark J. Kilgard \\
{\em Silicon Graphics, Inc.}}

\maketitle

%start on a different page for tutorial notes
%\setcounter{page}{220}

%\renewcommand{\thepage}{\roman{page}}

OpenGL is a trademark of Silicon Graphics, Inc.  X Window System is
a trademark of X Consortium, Inc.  Spaceball is a registered trademark
of Spatial Systems Inc.

The author has taken care in preparation of this documentation but makes no
expressed or implied warranty of any kind and assumes no 
responsibility for errors or omissions.  No liability is assumed
for incidental or consequential damages in connection with or arising
from the use of information or programs contained herein.

\vspace{.5in}

\begin{center}
Copyright \copyright 1994, 1995 Mark J. Kilgard.  All rights reserved.
\end{center}

\vspace{.5in}

All rights reserved.  No part of this documentation may be reproduced,
in any form or by any means, without permission in writing from the author.

\newpage

\tableofcontents

\cleardoublepage

%\setcounter{page}{1}

%\renewcommand{\thepage}{\arabic{page}}

\section{Introduction}

\def\Fortran{{\sc Fortran}}

The OpenGL Utility Toolkit (GLUT) is a programming interface with ANSI C and
\Fortran\ bindings for writing window system
independent OpenGL programs.  The toolkit supports the following functionality:
\begin{itemize}
\item Multiple windows for OpenGL rendering.
\item Callback driven event processing.
\item Sophisticated input devices.
\item An `idle' routine and timers.
\item A simple, cascading pop-up menu facility.
\item Utility routines to generate various solid and wire frame objects.
\item Support for bitmap and stroke fonts.
\item Miscellaneous window management functions.
\end{itemize}
An ANSI C implementation of GLUT for the X Window System \cite{x92} has
been implemented.

This documentation serves as both a specification and a programming guide.
If you are interested in a brief introduction to programming with GLUT,
look for the introductory OpenGL column \cite{kilgard94c}
published in {\em The X Journal}.

The remainder of this section describes GLUT's design philosophy and usage model.
The subsequent sections specify the GLUT routines, grouped by functionality.
The final sections discuss usage hints, the \Fortran\ binding, and implementation issues.
Appendix A enumerates and annotates the logical programmer visible state maintained by GLUT.
Appendix B presents the ANSI C GLUT API via its header file.
Appendix C presents the \Fortran\ GLUT API via its header file.

\subsection{Background}

One of the major accomplishments in the specification of OpenGL \cite{segal92,arb92}
was the
isolation of window system dependencies from OpenGL's rendering model.
The result is that OpenGL is window system independent.

Window system operations such as
the creation of a rendering window and the handling of window system
events are left to the native window system to define.
Necessary interactions between OpenGL and the window system such as creating
and binding an OpenGL context to
a window are described separately from the OpenGL specification in a
window system dependent specification.  For example, the GLX specification
\cite{karlton93}
describes the standard by which OpenGL interacts with the X Window System.

The predecessor to OpenGL is IRIS GL \cite{sgi91a,sgi91b}.
Unlike OpenGL, IRIS GL {\em does}
specify how rendering windows are created and manipulated.  IRIS GL's
windowing interface is reasonably popular largely because it is simple
to use.  IRIS GL programmers can worry about graphics programming without
needing to be an expert in programming the native window system.
Experience also demonstrated IRIS GL's windowing interface was high-level
enough that it could be retargeted to different window systems.  Silicon
Graphics migrated from NeWS to the X Window System without any major
changes to IRIS GL's basic windowing interface.

Removing window system operations from OpenGL is a sound decision
because it allows the OpenGL graphics system to be retargeted to
various systems including powerful but expensive graphics
workstations as well as mass-production graphics systems like video
games, set-top boxes for interactive television, and PCs.

Unfortunately, the lack of a window system interface for OpenGL
is a gap in OpenGL's utility.  Learning native window system APIs
such as the X Window System's Xlib \cite{kilgard94a} or
Motif \cite{kilgard94b} can be daunting.
Even those familiar with native window system APIs need to
understand the interface that binds OpenGL to the native window system.
And when an OpenGL program is written using the native window system
interface, despite the portability of the program's OpenGL rendering
code, the program itself will be window system dependent.

Testing and documenting OpenGL's functionality lead to
the development of the {\tt tk} and {\tt aux} toolkits.  The {\tt aux}
toolkit is used in the examples found in the {\em OpenGL Programming Guide}
\cite{neider93}.
Unfortunately, {\tt aux} has numerous limitations and its utility is
largely limited to toy programs.  The {\tt tk} library has
more functionality than {\tt aux} but was developed in an {\em ad hoc}
fashion and still lacks much important functionality that IRIS GL
programmers expect, like pop-up menus.

GLUT is designed to fill the need for a window system independent
programming interface for OpenGL programs.  The interface is designed
to be simple yet still meet the needs of useful OpenGL programs.
Features from the IRIS GL, {\tt aux}, and {\tt tk} interfaces are
included to make it easy for programmers used to these interfaces
to develop programs for GLUT.

\subsection{Design Philosophy}

GLUT simplifies the implementation of programs using OpenGL rendering.
The GLUT application programming interface (API) requires very few routines
to display a graphics scene rendered using OpenGL.  The GLUT API (like the OpenGL
API) is stateful.  Most initial GLUT state is defined and the
initial state is reasonable for simple programs.

The GLUT routines also take relatively few parameters.
No pointers are returned.  The only pointers passed into GLUT are character pointers
to strings (all strings passed to GLUT are copied, not referenced)
and opaque font handles.

The GLUT API is (as much as reasonable) window system independent.  For
this reason, GLUT does not return {\em any} native window system handles,
pointers, or other data structures.  More subtle window system dependencies
such as reliance on window system dependent fonts is avoided by GLUT; instead,
GLUT supplies its own (limited) set of fonts. 

% Reasonable leeway
% is granted implementations of GLUT for various window systems.  For window
% system interactions that may require guidance in implementation, the phrase
% ``The intent is'' will be used in this specification to describe the spirit of
% the intended window system interaction.

For programming ease, GLUT provides a simple menu sub-API.  While the menuing
support is designed to be implemented as pop-up menus, GLUT permits window system
constraints to support the menu functionality in another manner (pull-down menus
for example).

Two of the most important pieces of GLUT state are the {\em current window}
and {\em current menu}.  Most window and menu routines affect the {\em
current window} or {\em menu} respectively.  Most callbacks implicitly
set the {\em current window} and/or {\em menu} to the appropriate
window and/or menu responsible for the callback.  GLUT is designed
so that a program with only a single window and/or menu will not need
to keep track of any window or menu identifiers.  This greatly
simplifies very simple GLUT programs.

GLUT is designed for simple to moderately complex programs focused on OpenGL
rendering.  GLUT implements its own event loop.  For this reason, mixing GLUT
with other APIs that demand their own event handling structure may be difficult.
The advantage of a builtin event dispatch loop is simplicity.

GLUT contains routines for rendering fonts and geometric shapes.  GLUT makes
no claims on the OpenGL display list name space.  For this reason, none of the
GLUT rendering routines use OpenGL display lists.  It is up to the GLUT programmer
to compile the output from GLUT rendering routines into display lists
if this is desired.

GLUT routines are logically organized into several sub-APIs according
to their functionality.  The sub-APIs are:
\begin{description}
\item[\em Initialization.]
Command line processing,
window system initialization, and initial window creation state are controlled
by these routines.
\item[\em Beginning Event Processing.]
This routine enters GLUT's event processing loop.  This routine never returns
and continuously calls GLUT callbacks as necessary.
\item[\em Window Management.]
These routines create and control GLUT windows.
\item[\em Menu Management.]
These routines create and control GLUT pop-up menus.
\item[\em Callback Registration.]
These routines register callbacks to be called by the GLUT event processing loop.
\item[\em Color Index Colormap Management.]
These routines allow the manipulation of color index colormaps for windows.
\item[\em State Retrieval.]
These routines allows programs to retrieve state from GLUT.
\item[\em Font Rendering.]
These routines allow rendering of stroke and bitmap fonts.
\item[\em Geometric Shape Rendering.]
These routines allow the rendering of 3D geometric shapes including spheres,
cones, icosahedrons, and teapots.
\end{description}

\subsection{API Version 2}

In response to feedback from the original version of GLUT, GLUT API version
2 was developed.  Additions to the original GLUT API version 1 are:
\begin{itemize}
\item Support for requesting stereo and multisample windows.
\item New routines to query support for and provide callbacks for sophisticated
      input devices: Spaceball, tablet, and dial \& button box.
\item New routine to register a callback for keyboard function and directional
      keys.  In version 1, only ASCII characters could be generated.
\item New queries for stereo, multisampling, and elapsed time.
\item New routine to ease querying for OpenGL extension support.
\end{itemize}
GLUT API version 2 is completely compatible with version 1 of the API.
Version 1 programs should recompiled with GLUT API version 2 libraries
should need no source code changes.

\subsection{Conventions}

GLUT window and screen coordinates are expressed in pixels.  The upper left hand
corner of the screen or a window is (0,0).  X coordinates increase in a
rightward direction; Y coordinates increase in a downward direction.
Note:  This is inconsistent with OpenGL's coordinate scheme that generally
considers the lower left hand coordinate of a window to be at (0,0) but is
consistent with most popular window systems.

Integer identifiers in GLUT begin with one, not zero.  So window identifiers,
menu identifiers, and menu item indexes are based from one, not zero.

In GLUT's ANSI C binding, for most routines, basic types ({\tt int},
{\tt char*}) are used as parameters.  In routines where the parameters
are directly passed to OpenGL routines, OpenGL types ({\tt GLfloat})
are used.

The header files for GLUT should be included in GLUT programs
with the following include directive:
\begin{verbatim}
#include <GL/glut.h>
\end{verbatim}
Because a very large window system software vendor (who will remain
nameless) has an apparent inability to appreciate that OpenGL's API is
independent of their window system API, portable ANSI C GLUT programs should
not directly include {\tt <GL/gl.h>} or {\tt <GL/glu.h>}.  Instead,
ANSI C GLUT programs should rely on {\tt <GL/glut.h>} to include the necessary
OpenGL and GLU related header files.

The ANSI C GLUT library archive is typically named {\tt libglut.a} on Unix
systems.  GLUT programs need to link with the system's OpenGL and GLUT libraries
(and any libraries these libraries potentially depend on).
A set of window system dependent libraries may also be necessary
for linking GLUT programs.  For example, programs using the X11 GLUT
implementation typically need to link with Xlib, the X extension
library, possibly the X Input extension library,  the X miscellaneous
utilities library, and the math library.  An example X11/Unix
compile line would look like:
\begin{verbatim}
  cc -o foo foo.c -lglut -lGLU -lGL -lXmu -lXi -lXext -lX11 -lm
\end{verbatim}

\subsection{Terminology}

A number of terms are used in a GLUT-specific manner throughout this
document.  The GLUT meaning of these terms is independent of the
window system GLUT is implemented for.  Here are GLUT-specific
meanings for the following GLUT-specific terms:
\begin{description}
\item[\em \ndx{Callback}]  A programmer specified routine that can be
registered with GLUT to be called in response to a specific type
of event.  Also used to refer to a specific callback routine
being called.
\item[\em \ndx{Dials and button box}]  A sophisticated input device
consisting of a pad of buttons and an array of rotating dials.
\item[\em \ndx{Display mode}]  A set of OpenGL frame buffer capabilities
that can be attributed to a window.
\item[\em \ndx{Idle}]  A state when no window system events are received
for processing as callbacks and the idle callback, if registered,
is called.
\item[\em \ndx{Menu entry}]  A menu item that the user can select to
trigger the menu callback for the menu entry's value.
\item[\em \ndx{Menu item}]  Either a menu entry or a sub-menu trigger.
\item[\em \ndx{Multisampling}]  A technique for hardware antialiasing
generally available only on expensive 3D graphics hardware.  Each
pixel is composed of a number of samples (each containing color and
depth information).  The samples are averaged to determine the
displayed pixel color value.  Multisampling is supported as an
extension to OpenGL.
\item[\em \ndx{Pop}]  The act of forcing a window to the top of the
stacking order for sibling windows.
\item[\em \ndx{Pop-up menu}]  A menu that can be set to appear when a specified
mouse button is pressed in a window.  A pop-menu consists of multiple
menu items.
\item[\em \ndx{Push}]  The act of forcing a window to the bottom of the
stacking order for sibling windows.
\item[\em \ndx{Reshape}]  The act of changing the size or shape of the window.
\item[\em \ndx{Spaceball}]  A sophisticated 3D input device that provides 3
axes of rotation and 3 axes of translation.  It also supports a number
of buttons.  The device is a hand-sized ball attached to a base.  By
cupping the ball with one's hand and applying twisting or directional force
on the ball, translations and rotations are generated.
\item[\em \ndx{Sub-menu}]  A menu cascaded from some sub-menu trigger.
\item[\em \ndx{Sub-menu trigger}]  A menu item that the user can enter to
cascade another pop-up menu to select more menu choices.
\item[\em \ndx{Subwindow}]  A type of window that is the child window of
top-level window or other subwindow.  The drawing and visible region
of a subwindow is limited by its parent window.
\item[\em \ndx{Tablet}]  A sophisticated, precised 2D input device.  Like
a mouse, 2D coordinates are returned.  The absolute position of the
tablet ``puck'' on the tablet is returned.  Tablets also support
a number of buttons.
\item[\em \ndx{Timer}]  A callback that can be scheduled to be called in
a specified interval of time.
\item[\em \ndx{Top-level window}]  A window that can be placed, moved, resized,
etc. independently from other top-level windows by the user.
Subwindows may reside within a top-level window.
\item[\em \ndx{Window}]  A rectangular area for OpenGL rendering.
\item[\em \ndx{Window display state}]  One of shown, hidden, or iconified.
A shown window is potentially visible on the screen (it may be obscured
by other windows and not actually visible); a hidden window will
never be visible; and iconified window is not visible but could
be made visible in response to some user action like clipping the
window's corresponding icon.
\item[\em \ndx{Window system}]  The broad notion of the window system
that refers to both the mechanism and policy of the window system.
For example, in the X Window System both the window manager and the
X server are integral to what GLUT considers the window system.
\end{description}

\input glutapi.tex

\section{Usage Advice}

Some hints when programming with GLUT:

\begin{itemize}

\item
Do not change state that will affect the way a window
will be drawn in a window's display callback.
Your display callback should be idempotent.

\item
If you need to redisplay a window, instead of rendering in
whatever callback you happen to be in, call \rndx{glutPostRedisplay}.
As a general rule, the only code that renders directly to the screen
should be in called from display callbacks; other types of callbacks
should not be rendering to the screen.

\item
If you use an idle callback to control your animation, use the
visibility callbacks to determine when the window is fully obscured
or iconified to determine when not to waste processor time rendering.

\item
Avoid using color index mode if possible.

\item
For most callbacks, the {\em current window} and/or {\em current menu} is
set appropriately at the time of the callback.  Timer and idle callbacks
are exceptions.  If your application uses multiple windows or menus,
make sure in idle and timer callback you explicitly set the
window or menu appropriately using \rndx{glutSetWindow} and \rndx{glutSetMenu}.

\item
If you register a single function as a callback routine for multiple
windows, you can call \rndx{glutGetWindow} within the callback to
determine what window is generating the callback.  Likewise, \rndx{glutGetMenu} can be called to determine what menu.

\item
By default, timer and idle callbacks may be called while a
pop-up menu is active.  On slow machines, slow rendering in an idle
callback may compromise menu performance.  Also, it may be desirable
for motion to stop immediately when a menu is triggered.  In this
case, use the menu entry/exit callback set with \rndx{glutMenuStateFunc}
to track the usage of pop-up menus.

\item
Do not select for more input callbacks than you actually
need.  For example, if you do not need motion or passive motion
callbacks, disable them by passing {\tt NULL} to their callback
register functions.  Disabling input callbacks allows the GLUT
implementation to limit the window system input events that must
be processed.

\item
Not every OpenGL implementation supports the same range of
frame buffer capabilities though minimum requirements for
frame buffer capabilities do exist.  If \rndx{glutCreateWindow}
or \rndx{glutCreateSubWindow} are called with an {\em initial
display mode} not supported by the OpenGL implementation,
a fatal error will be generated with an explanatory message.
To avoid this, \rndx{glutGet(GLUT\_DISPLAY\_MODE\_POSSIBLE)}
should be called to determine if the {\em initial
display mode} is supported by the OpenGL implementation.

The Backspace, Delete, and Escape keys generate ASCII characters so detect
key presses for these keys using the \rndx{glutKeyboardFunc} callback, not
with the \rndx{glutSpecialFunc} callback.

\item
Remember to it is illegal to create or destroy menus or change, add, or
remove menu items while a menu (and any cascaded sub-menus) are in use
(i.e., popped up).  Use the menu status callback to know when to
avoid menu manipulation.

\item
Definitely, definitely, use the {\tt -gldebug} option to look
for OpenGL errors when OpenGL rendering does not appear to
be operating properly.  OpenGL errors are only reported if
you explicitly look for them!

\end{itemize}

\section{FORTRAN Binding}

All GLUT functionality is available through the GLUT \Fortran\ API.
The GLUT \Fortran\ binding is intended to be used in conjunction with the OpenGL and GLU
\Fortran\ APIs.

A \Fortran\ routine using GLUT routines should include the GLUT \Fortran\
header file.  While this is potentially system dependent, on Unix
systems this is normally done by including after the {\tt SUBROUTINE},
{\tt FUNCTION}, or {\tt PROGRAM} line:
\begin{verbatim}
#include "GL/fglut.h"
\end{verbatim}

The GLUT \Fortran\ binding (and the OpenGL and GLU \Fortran\ bindings)
assume identifiers are not limited to 6 characters.

\subsection{Names for the FORTRAN GLUT Binding}

Allowing for {\sc Fortran}'s case-insensitivity, the GLUT \Fortran\ binding
constant and routine names are the same as the C binding's names.

The ARB's official OpenGL \Fortran\ API prefixes every routine and
constant with the letter F.  The justification was to avoid name
space collisions with the C names in anachronistic compilers.  Nearly
all modern \Fortran\ compilers avoid these name space clashes via other
means (underbar suffixing of \Fortran\ routines is used by most Unix \Fortran\
compilers).

The GLUT \Fortran\ API does {\em not} use such prefixing conventions
because of the documentation and coding confusion introduced by
such prefixes.  The confusion is heightened by
{\sc Fortran}'s default implicit variable initialization so programmers
may realize the lack of a constant prefix as a result of a run-time error.
The confusion introduced to support the prefixes
was not deemed worthwhile simply to support anachronistic
compliers.

The OpenGL ARB's official \Fortran\ binding for the GLU and OpenGL APIs
that chose to prefix the letter {\tt F} before every OpenGL and GLU
constant and routine name.  

\subsection{Font Naming Caveat}

Because GLUT fonts are compiled directly into GLUT programs as data,
and programs should only have the fonts compiled into them that they use,
GLUT font names like {\tt GLUT\_BITMAP\_TIMES\_ROMAN\_24} are really
symbols so the linker should only pull in used fonts.

Unfortunately, because some supposedly modern \Fortran\ compilers
link declared but unused data EXTERNALs, ``GL/fglut.h'' does not
explicitly declare EXTERNAL the GLUT font symbols.  Declaring the
GLUT font symbols as 
EXTERNAL risks forcing every GLUT \Fortran\
program to contain the data for every GLUT font.  GLUT
Fortran programmers should explicitly declare EXTERNAL
the GLUT fonts they use.  Example:
\begin{verbatim}
        SUBROUTINE PRINTA
#include "GL/fglut.h"
        EXTERNAL GLUT_BITMAP_TIMES_ROMAN_24
        CALL glutBitmapCharacter(GLUT_BITMAP_TIMES_ROMAN_24, 65)
        END
\end{verbatim}

\subsection{NULL Callback}

\Fortran\ does not support passing {\tt NULL} as a callback
parameter the way ANSI C does.  For this reason, {\tt GLUTNULL}
is used in place of {\tt NULL} in GLUT \Fortran\ programs to
indicate a {\tt NULL} callback.

\section{Implementation Issues}

While this specification is primarily intended to describe the GLUT API
and not its implementation, the section describes implementation
issues that are likely to help both GLUT implementors properly
implement GLUT and provide GLUT programmers with information to better
utilize GLUT.

\subsection{Name Space Conventions}

The GLUT implementation should have a well-defined name space for both
exported symbols and visible, but not purposefully exported symbols.
All exported functions are prefixed by {\tt glut}.  All exported macro
definitions are prefixed by {\tt GLUT\_}.  No data symbols are
exported.  All internal symbols that might be user-visible but not
intended to be exported should be prefixed by {\tt \_\_glut}.  Users of
the GLUT API should {\em not} use any {\tt \_\_glut} prefixed symbols.

\newpage

\appendix

%\mbox{}\\
%\vspace{1.5in}

\section{GLUT State}

\input glut_state.tex

\section{glut.h ANSI C Header File}

{\footnotesize
\verbatimlisting{glut.h.notab}
}

\section{fglut.h FORTRAN Header File}

{\footnotesize
\verbatimlisting{fglut.h.notab}
}

\newpage

\addcontentsline{toc}{section}{References}

\begin{thebibliography}{99}

\bibitem{karlton93} Phil Karlton, {\em OpenGL Graphics with the X
Window System}, Ver. 1.0, Silicon Graphics, April 30, 1993.

\bibitem{kilgard93}
Mark Kilgard, ``Programming X Overlay Windows,'' {\em The X Journal},
SIGS Publications, July 1993.

\bibitem{kilgard94a}
Mark Kilgard, ``OpenGL and X, Part 2: Using OpenGL with Xlib,''
{\em The X Journal}, SIGS Publications, Jan/Feb 1994.

\bibitem{kilgard94b}
Mark Kilgard, ``OpenGL and X, Part 3: Integrating OpenGL with Motif,''
{\em The X Journal}, SIGS Publications, Jul/Aug 1994.

\bibitem{kilgard94c}
Mark Kilgard, ``An OpenGL Toolkit,''
{\em The X Journal}, SIGS Publications, Nov/Dec 1994.

\bibitem{neider93}
Jackie Neider, Tom Davis, Mason Woo, {\em OpenGL Programming Guide:
The official guide to learning OpenGL, Release 1}, Addison Wesley, 1993.

\bibitem{arb92}
OpenGL Architecture Review Board, {\em OpenGL Reference Manual:  The
official reference document for OpenGL, Release 1}, Addison Wesley, 1992.

\bibitem{xinput-lib}
Mark Patrick, George Sachs, {\em X11 Input Extension Library Specification}, 
X Consortium Standard, X11R6, April 18, 1994.

\bibitem{xinput-protocol}
Mark Patrick, George Sachs, {\em X11 Input Extension Protocol Specification}, 
X Consortium Standard, X11R6, April 17, 1994.

\bibitem{x92}
Robert Scheifler, James Gettys, {\em X Window System: The complete Reference
to Xlib, X Protocol, ICCCM, XLFD}, third edition, Digital Press, 1992.

\bibitem{segal92}
Mark Segal, Kurt Akeley, {\em The OpenGL${}^{\rm TM}$ Graphics System:
A Specification}, Version 1.0, Silicon Graphics, June 30, 1992.

\bibitem{sgi91a}
Silicon Graphics, {\em Graphics Library Programming Guide},
Document Number 007-1210-040, 1991.

\bibitem{sgi91b}
Silicon Graphics, {\em Graphics Library Window and Font Library Guide},
Document Number 007-1329-010, 1991.

\end{thebibliography}

\newpage

\addcontentsline{toc}{section}{Index}
\input spec2.ind

\end{document}

